What’s Next?

So far, we’ve learned about all the aspects of designing an intuitive API that’s easy to use and implement. We’ve explored designing APIs for various foundational and advanced design problems and looked at the best practices for designing robust and scalable APIs. These APIs can meet the needs of a wide range of users according to defined functional requirements. Moving forward, let’s take a look at what next steps we can take after gaining expertise in API designs. The following sections discuss the sequence of the steps to take after the API design is ready, starting with the implementation of the API design.

Implementation#

The two approaches that are used for the implementation of APIs are given below:

• Design-first approach

• Code-first approach

The following illustration explains the difference between the two approaches:

In this course, we opted for the design-first approach and defined all the various aspects of API designs using the REDCAMEL approach. All the functional and non-functional requirements, design considerations, API model, and latency budget estimation are explained in detail in each design problem. Once all the aspects have been clearly defined and agreed upon, the next step is implementing the API design through coding. A careful selection of programming languages to develop an API can improve the development experience. Once the API has been developed, it’s ready for testing, as discussed in the following section.

Testing#

API testing comprises the process of verifying that an API is generating the desired results for the defined requests as outlined in the API design requirements. The testing enables developers to mitigate any issue in an API's performance and results before making it publicly available. API testing includes the following testing types:

Automated vs. manual testing#

Manual API testing allows the tester to directly test an API's behavior using tools such as Postman and Talend API tester, or a user interface. Manual testing requires more effort and time for the QA because they’ll need to test the API every time there is a slight change made to it. In contrast, automated testing involves testing APIs using specialized software that evaluates different aspects of the behavior of the API using predefined tests. This type of testing is less time consuming, but is more costly because these tests need to be written and maintained with the changes in the API code. So, we have to decide which one to use according to our needs.

Best practices of API testing #

• Group similar tests: Grouping tests by functionality makes it easier to maintain tests for a large-scale application in the future.

• Test all use cases: We should ensure all use cases related to our requirements are tested well.

• Automation: Automation makes the testing process fast and efficient and is preferred over manual testing. An API testing tool is used to perform automatic testing.

• Realistic tests: We should try to make tests with data that’s closest to conditions that the API will encounter when it’s live.

• Simple, small, and easy-to-maintain tests: Compared to complex tests, simple and small tests are easy to maintain and can efficiently be updated as the APIs evolve.

Benefits of API testing#

• Earlier detection: APIs are usually developed before user interfaces. Because of this, we can detect a problem in the workflow earlier by testing the API. In addition, if we also have automated testing, the testing process becomes even faster.

• Better security: API testing can detect potential flaws in the security of an API, reducing the risks of API failure.

• Better integration: When an API is tested well, it facilitates easy integration with user interfaces.

We expect errors to be detected during API testing. Mostly, these errors are prominent, making it easy to identify the reasons; but in a few cases, it’s difficult to find out the root cause of the error. In these scenarios, debugging helps detect the root cause of the error, as discussed in the next section.

Debugging#

Debugging is the process of detecting an error in the functionality or performance of an API. This process is quite tricky. Sometimes, it may take a lot of time to find the root cause of an error or problem. Sometimes, the error is immediately identified and reported.

• If an invalid request causes the error, a user should carefully observe the requests and their formats. There can be an incorrect request type, malfunctioning JSON body, wrong authentication, incorrect Content-Type headers, and so on.

• If the responses are not according to the requirements, there could be an issue with API execution flow or business logic.

• If there’s a serialization error, it could be due to incorrect encoding and decoding of JSON objects.

API debugging strategies#

Some important strategies to debug an error in an API are mentioned below:

• Check the status code
  Status codes give a good idea of the problem. We can search which problems return a certain response code and identify the issue quickly. Though these errors are discussed thoroughly in all design problems, the table below revises some of the most commonly occurring status codes and their related errors.

• Check logs
  If an error has occurred on the server-side, we can try to validate values through API logs. Log points are the points in code where messages are logged/written to trace errors or code execution. If the application has sufficient and correct log points, then it can help us find the problem sooner.

It’s recommended that we document the API once all the testing and debugging processes have been completed before making it publicly available.

Documentation#

API documentation is a manual that explains how to use an API and its services. This manual might contain instructions, screenshots, and code examples for using an API. It’s also used as a contract between the consumer and developer parties. All the API calls are documented in it, which explains the requests and their responses.

The following are some best practices for writing good documentation:

• Consider the target audience: The audience, such as developers (inside or outside the company), technical writers, non-technical clients using APIs, and so on, is the main factor to consider when writing API documentation. The better it explains things, the easier it will be to use by consumers.

• Explain the usage of API: The document should explain the purpose of the API, how to use it, and the language and protocols it uses.

• Explain the functions, endpoints, and responses of the API: It should explain all the functions and endpoints of the API as well as the requests and their responses in detail.

• Provide code examples and screenshots: Adding code examples to call an API and screenshots explaining the requests and their responses can help users better understand how to use an API.

• List out response codes: We should list all the response codes and bodies for each request. We should also mention the error response code that we could expect from the API.

• Provide authentication details: The authentication methods used by the API should also be mentioned.

• Explain headers: The API documentation should explain each header and its purpose to users, such as the headers for authentication and authorization, data formats, and so on.

• Provide all required parameters: The bad request error usually occurs due to invalid parameters or headers while sending a request. The parameters that are either required or optional for an API call should be adequately explained.

• Mention rate limit: Rate limit is the number of times a user can send an API request in a particular amount of time, and it’s an important piece of information to provide.

• Make a changelog: A changelog contains all the changes made in the API. It’s good to make a section for it in the API documentation so that users can track changes and keep their applications up to date for better API consumption.

• Update documentation: Update the documentation regularly throughout the development process because outdated documentation may confuse the consumers and users, making the API useless.

Summary#

API code implementation is the next step after mastering API design in a design-first approach. Implementation involves selecting an appropriate programming language and framework, writing code for all the endpoints according to their defined functionality, using a proper naming convention for endpoints, and developing it according to the industry's modern standards. In testing, the behavior of developed APIs is checked according to the requirements, expected output, and error codes with their messages. Additionally, if finding an error becomes challenging while testing, debugging is applied in order to find the root cause and solve it accordingly.